home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Languguage OS 2
/
Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO
/
gnu
/
elispman.lha
/
elispman
/
elisp-21
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-06-01
|
49KB
|
910 lines
This is Info file elisp, produced by Makeinfo-1.55 from the input file
elisp.texi.
This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 19.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: elisp, Node: X Frame Parameters, Next: Size And Position, Prev: Initial Parameters, Up: Frame Parameters
X Window Frame Parameters
-------------------------
Just what parameters a frame has depends on what display mechanism it
uses. Here is a table of the parameters of an X window frame:
`name'
The name of the frame.
`left'
The screen position of the left edge, in pixels.
`top'
The screen position of the top edge, in pixels.
`height'
The height of the frame contents, in pixels.
`width'
The width of the frame contents, in pixels.
`window-id'
The number of the X window for the frame.
`minibuffer'
Whether this frame has its own minibuffer. The value `t' means
yes, `nil' means no, `only' means this frame is just a minibuffer,
a minibuffer window (in some other frame) means the new frame uses
that minibuffer.
`font'
The name of the font for text in the frame. This is a string.
`auto-raise'
Whether selecting the frame raises it (non-`nil' means yes).
`auto-lower'
Whether deselecting the frame lowers it (non-`nil' means yes).
`vertical-scroll-bars'
Whether the frame has a scroll bar for vertical scrolling
(non-`nil' means yes).
`horizontal-scroll-bars'
Whether the frame has a scroll bar for horizontal scrolling
(non-`nil' means yes). (Horizontal scroll bars are not currently
implemented.)
`icon-type'
The type of icon to use for this frame when it is iconified.
Non-`nil' specifies a bitmap icon, `nil' a text icon.
`foreground-color'
The color to use for the inside of a character. We use strings to
designate colors; the X server defines the meaningful color names.
`background-color'
The color to use for the background of text.
`mouse-color'
The color for the mouse cursor.
`cursor-color'
The color for the cursor that shows point.
`border-color'
The color for the border of the frame.
`cursor-type'
The way to display the cursor. There are two legitimate values:
`bar' and `box'. The value `bar' specifies a vertical bar between
characters as the cursor. The value `box' specifies an ordinary
black box overlaying the character after point; that is the
default.
`border-width'
The width in pixels of the window border.
`internal-border-width'
The distance in pixels between text and border.
`unsplittable'
If non-`nil', this frame's window is never split automatically.
`visibility'
The state of visibility of the frame. There are three
possibilities: `nil' for invisible, `t' for visible, and `icon' for
iconified. *Note Visibility of Frames::.
`menu-bar-lines'
The number of lines to allocate at the top of the frame for a menu
bar. The default is zero. *Note Menu Bar::.
`parent-id'
The X Window number of the window that should be the parent of
this one. Specifying this lets you create an Emacs window inside
some other application's window. (It is not certain this will be
implemented; try it and see if it works.)
File: elisp, Node: Size And Position, Prev: X Frame Parameters, Up: Frame Parameters
Frame Size And Position
-----------------------
You can read or change the size and position of a frame using the
frame parameters `left', `top', `height' and `width'. When you create
a frame, you must specify either both size parameters or neither.
Likewise, you must specify either both position parameters or neither.
Whatever geometry parameters you don't specify are chosen by the window
manager in its usual fashion.
Here are some special features for working with sizes and positions:
- Function: set-frame-position FRAME LEFT TOP
This function sets the position of the top left corner of
FRAME--to LEFT and TOP. These arguments are measured in pixels,
counting from the top left corner of the screen.
- Function: frame-height &optional FRAME
- Function: frame-width &optional FRAME
These functions return the height and width of FRAME, measured in
characters. If you don't supply FRAME, they use the selected
frame.
- Function: frame-pixel-height &optional FRAME
- Function: frame-pixel-width &optional FRAME
These functions return the height and width of FRAME, measured in
pixels. If you don't supply FRAME, they use the selected frame.
- Function: frame-char-height &optional FRAME
- Function: frame-char-width &optional FRAME
These functions return the height and width, respectively, of a
character in FRAME, measured in pixels. The values depend on the
choice of font. If you don't supply FRAME, these functions use
the selected frame.
- Function: set-frame-size FRAME COLS ROWS
This function sets the size of FRAME, measured in characters; COLS
and ROWS specify the new width and height.
To set the size with values measured in pixels, use
`modify-frame-parameters' to set the `width' and `height'
parameters. *Note X Frame Parameters::.
The old-fashioned functions `set-screen-height' and
`set-screen-width', which were used to specify the height and width of
the screen in Emacs versions that did not support multiple frames, are
still usable. They apply to the selected frame. *Note Screen Size::.
- Function: x-parse-geometry GEOM
The function `x-parse-geometry' converts a standard X windows
geometry string to an alist which you can use as part of the
argument to `x-create-frame'.
The alist describes which parameters were specified in GEOM, and
gives the values specified for them. Each element looks like
`(PARAMETER . VALUE)'. The possible PARAMETER values are `left',
`top', `width', and `height'.
(x-geometry "35x70+0-0")
=> ((width . 35) (height . 70) (left . 0) (top . -1))
File: elisp, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Parameters, Up: Frames
Deleting Frames
===============
Frames remain potentially visible until you explicitly "delete"
them. A deleted frame cannot appear on the screen, but continues to
exist as a Lisp object until there are no references to it. There is no
way to cancel the deletion of a frame aside from restoring a saved frame
configuration (*note Frame Configurations::.); this is similar to the
way windows behave.
- Command: delete-frame &optional FRAME
This function deletes the frame FRAME. By default, FRAME is the
selected frame.
- Function: frame-live-p FRAME
The function `frame-live-p' returns non-`nil' if the frame FRAME
has not been deleted.
File: elisp, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
Finding All Frames
==================
- Function: frame-list
The function `frame-list' returns a list of all the frames that
have not been deleted. It is analogous to `buffer-list' for
buffers. The list that you get is newly created, so modifying the
list doesn't have any effect on the internals of Emacs.
- Function: visible-frame-list
This function returns a list of just the currently visible frames.
- Function: next-frame &optional FRAME MINIBUF
The function `next-frame' lets you cycle conveniently through all
the frames from an arbitrary starting point. It returns the "next"
frame after FRAME in the cycle. If FRAME is omitted or `nil', it
defaults to the selected frame.
The second argument, MINIBUF, says which frames to consider:
`nil'
Exclude minibuffer-only frames.
a window
Consider only the frames using that particular window as their
minibuffer.
anything else
Consider all frames.
File: elisp, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
Frames and Windows
==================
All the non-minibuffer windows in a frame are arranged in a tree of
subdivisions; the root of this tree is available via the function
`frame-root-window'. Each window is part of one and only one frame;
you can get the frame with `window-frame'.
- Function: frame-root-window FRAME
This returns the root window of frame FRAME.
- Function: window-frame WINDOW
This function returns the frame that WINDOW is on.
At any time, exactly one window on any frame is "selected within the
frame". The significance of this designation is that selecting the
frame also selects this window. You can get the frame's current
selected window with `frame-selected-window'.
- Function: frame-selected-window FRAME
This function returns the window on FRAME which is selected within
FRAME.
Conversely, selecting a window for Emacs with `select-window' also
makes that window selected within its frame. *Note Selecting Windows::.
File: elisp, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
Minibuffers and Frames
======================
Normally, each frame has its own minibuffer window at the bottom,
which is used whenever that frame is selected. If the frame has a
minibuffer, you can get it with `minibuffer-window' (*note Minibuffer
Misc::.).
However, you can also create a frame with no minibuffer. Such a
frame must use the minibuffer window of some other frame. When you
create the frame, you can specify explicitly the frame on which to find
the minibuffer to use. If you don't, then the minibuffer is found in
the frame which is the value of the variable
`default-minibuffer-frame'. Its value should be a frame which does
have a minibuffer.
File: elisp, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
Input Focus
===========
At any time, one frame in Emacs is the "selected frame". The
selected window always resides on the selected frame.
- Function: selected-frame
This function returns the selected frame.
The X server normally directs keyboard input to the X window that the
mouse is in. Some window managers use mouse clicks or keyboard events
to "shift the focus" to various X windows, overriding the normal
behavior of the server.
Lisp programs can switch frames "temporarily" by calling the
function `select-frame'. This does not override the window manager;
rather, it escapes from the window manager's control until that control
is somehow reasserted.
- Function: select-frame FRAME
This function selects frame FRAME, temporarily disregarding the X
Windows focus. The selection of FRAME lasts until the next time
the user does something to select a different frame, or until the
next time this function is called.
Emacs cooperates with the X server and the window managers by
arranging to select frames according to what the server and window
manager ask for. It does so by generating a special kind of input
event, called a "focus" event. The command loop handles a focus event
by calling `internal-select-frame'. *Note Focus Events::.
- Function: internal-select-frame FRAME
This function selects frame FRAME, assuming that the X server
focus already points to FRAME.
Focus events normally do their job by invoking this command.
Don't call it for any other reason.
File: elisp, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
Visibility of Frames
====================
A frame may be "visible", "invisible", or "iconified". If it is
visible, you can see its contents. If it is iconified, the frame's
contents do not appear on the screen, but an icon does. If the frame
is invisible, it doesn't show in the screen, not even as an icon.
- Command: make-frame-visible &optional FRAME
This function makes frame FRAME visible. If you omit FRAME, it
makes the selected frame visible.
- Command: make-frame-invisible &optional FRAME
This function makes frame FRAME invisible. If you omit FRAME, it
makes the selected frame invisible.
- Command: iconify-frame &optional FRAME
This function iconifies frame FRAME. If you omit FRAME, it
iconifies the selected frame.
- Function: frame-visible-p FRAME
This returns the visibility status of frame FRAME. The value is
`t' if FRAME is visible, `nil' if it is invisible, and `icon' if
it is iconified.
The visibility status of a frame is also available as a frame
parameter. You can read or change it as such. *Note X Frame
Parameters::.
File: elisp, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
Raising and Lowering Frames
===========================
The X window system uses a desktop metaphor. Part of this metaphor
is the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from "highest" to
"lowest". Where two windows overlap, the one higher up covers the one
underneath. Even a window at the bottom of the stack can be seen if no
other window overlaps it.
A window's place in this ordering is not fixed; in fact, users tend
to change the order frequently. "Raising" a window means moving it
"up", to the top of the stack. "Lowering" a window means moving it to
the bottom of the stack. This motion is in the notional third
dimension only, and does not change the position of the window on the
screen.
You can raise and lower Emacs's X windows with these functions:
- Function: raise-frame FRAME
This function raises frame FRAME.
- Function: lower-frame FRAME
This function lowers frame FRAME.
You can also specify auto-raise (raising automatically when a frame
is selected) or auto-lower (lowering automatically when it is
deselected) for any frame using frame parameters. *Note X Frame
Parameters::.
File: elisp, Node: Frame Configurations, Next: Mouse Tracking, Prev: Raising and Lowering, Up: Frames
Frame Configurations
====================
- Function: current-frame-configuration
This function returns a "frame configuration" list which describes
the current arrangement of frames, all their properties, and the
window configuration of each one.
- Function: set-frame-configuration CONFIGURATION
This function restores the state of frames described in
CONFIGURATION.
File: elisp, Node: Mouse Tracking, Next: Mouse Position, Prev: Frame Configurations, Up: Frames
Mouse Tracking
==============
Sometimes it is useful to "track" the mouse, which means, to display
something to indicate where the mouse is and move the indicator as the
mouse moves. For efficient mouse tracking, you need a way to wait until
the mouse actually moves.
The convenient way to track the mouse is to ask for events to
represent mouse motion. Then you can wait for motion by waiting for an
event. In addition, you can easily handle any other sorts of events
that may occur. That is useful, because normally you don't want to
track the mouse forever--only until some other event, such as the
release of a button.
- Special Form: track-mouse BODY...
Execute BODY, meanwhile generating input events for mouse motion.
The code in BODY can read these events with `read-event' or
`read-key-sequence'. *Note Motion Events::, for the format of
mouse motion events.
The value of `track-mouse' is that of the last form in BODY.
The usual purpose of tracking mouse motion is to indicate on the
screen the consequences of pushing or releasing a button at the current
position.
File: elisp, Node: Mouse Position, Next: Pop-Up Menus, Prev: Mouse Tracking, Up: Frames
Mouse Position
==============
The new functions `mouse-position' and `set-mouse-position' give
access to the current position of the mouse.
- Function: mouse-position
This function returns a description of the position of the mouse.
The value looks like `(FRAME X . Y)', where X and Y are integers
giving the position in pixels relative to the top left corner of
the inside of FRAME.
- Function: set-mouse-position FRAME X Y
Thus function "warps the mouse" to position X, Y in frame FRAME.
The arguments X and Y are integers, giving the position in pixels
relative to the top left corner of the inside of FRAME.
Warping the mouse means changing the screen position of the mouse
as if the user had moved the physical mouse--thus simulating the
effect of actual mouse motion.
File: elisp, Node: Pop-Up Menus, Next: X Selections, Prev: Mouse Position, Up: Frames
Pop-Up Menus
============
- Function: x-popup-menu POSITION MENU
This function displays a pop-up menu and returns an indication of
what selection the user makes.
The argument POSITION specifies where on the screen to put the
menu. It can be either a mouse button event (which says to put
the menu where the user actuated the button) or a list of this
form:
((XOFFSET YOFFSET) WINDOW)
where XOFFSET and YOFFSET are positions measured in characters,
counting from the top left corner of WINDOW's frame.
The argument MENU says what to display in the menu. It can be a
keymap or a list of keymaps (*note Menu Keymaps::.).
Alternatively, it can have the following form:
(TITLE PANE1 PANE2...)
where each pane is a list of form
(TITLE (LINE ITEM)...)
Each LINE should be a string, and each ITEM should be the value to
return if that LINE is chosen.
File: elisp, Node: X Selections, Next: X Server, Prev: Pop-Up Menus, Up: Frames
X Selections
============
The X server records a set of "selections" which permit transfer of
data between application programs. The various selections are
distinguished by "selection types", represented in Emacs by symbols. X
clients including Emacs can read or set the selection for any given
type.
- Function: x-set-selection TYPE DATA
This function sets a "selection" in the X server. It takes two
arguments: a selection type TYPE, and the value to assign to it,
DATA. If DATA is `nil', it means to clear out the selection.
Otherwise, DATA may be a string, a symbol, an integer (or a cons
of two integers or list of two integers), or a cons of two markers
pointing to the same buffer. In the last case, the selection is
considered to be the text between the markers. The data may also
be a vector of valid non-vector selection values.
Each possible TYPE has its own selection value, which changes
independently. The usual values of TYPE are `PRIMARY' and
`SECONDARY'; these are symbols with upper-case names, in accord
with X Windows conventions. The default is `PRIMARY'.
- Function: x-get-selection TYPE DATA-TYPE
This function accesses selections set up by Emacs or by other X
clients. It takes two optional arguments, TYPE and DATA-TYPE.
The default for TYPE, the selection type, is `PRIMARY'.
The DATA-TYPE argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into
Lisp data. Meaningful values include `TEXT', `STRING', `TARGETS',
`LENGTH', `DELETE', `FILE_NAME', `CHARACTER_POSITION',
`LINE_NUMBER', `COLUMN_NUMBER', `OWNER_OS', `HOST_NAME', `USER',
`CLASS', `NAME', `ATOM', and `INTEGER'. (These are symbols with
upper-case names in accord with X conventions.) The default for
DATA-TYPE is `STRING'.
The X server also has a set of numbered "cut buffers" which can
store text or other data being moved between applications. Cut buffers
are considered obsolete, but Emacs supports them for the sake of X
clients that still use them.
- Function: x-get-cut-buffer N
This function returns the contents of cut buffer number N.
- Function: x-set-cut-buffer STRING
This function stores STRING into the first cut buffer (cut buffer
0), moving the other values down through the series of cut buffers,
kill-ring-style.
File: elisp, Node: X Server, Prev: X Selections, Up: Frames
X Server
========
This section describes how to access and change the overall status of
the X server Emacs is using.
* Menu:
* X Connections:: Opening and closing the X server connection.
* Resources:: Getting resource values from the server.
* Rebinding X Keys:: Telling the server what input to send
for each keyboard key.
* Server Data:: Getting info about the X server.
File: elisp, Node: X Connections, Next: Resources, Up: X Server
X Connections
-------------
You can close the connection with the X server with the function
`x-close-current-connection', and open a new one with
`x-open-connection' (perhaps with a different server and display).
- Function: x-close-current-connection
This function closes the connection to the X server. It deletes
all frames, making Emacs effectively inaccessible to the user;
therefore, a Lisp program that closes the connection should open
another one.
- Function: x-open-connection DISPLAY &optional RESOURCE-STRING
This function opens a connection to an X server, for use of display
DISPLAY.
The optional argument RESOURCE-STRING is a string of resource
names and values, in the same format used in the `.Xresources'
file. The values you specify override the resource values
recorded in the X server itself. Here's an example of what this
string might look like:
"*BorderWidth: 3\n*InternalBorder: 2\n"
- Function: x-color-display-p
This returns `t' if the connected X display has color, and `nil'
otherwise.
- Function: x-color-defined-p COLOR
This function reports whether a color name is meaningful and
supported on the X display Emacs is using. It returns `t' if the
display supports that color; otherwise, `nil'.
Black-and-white displays support just two colors, `"black"' or
`"white"'. Color displays support many other colors.
- Function: x-synchronize FLAG
The function `x-synchronize' enables or disables synchronous
communication with the X server. It enables synchronous
communication if FLAG is non-`nil', and disables it if FLAG is
`nil'.
In synchronous mode, Emacs waits for a response to each X protocol
command before doing anything else. This is useful for debugging
Emacs, because protocol errors are reported right away, which
helps you find the erroneous command. Synchronous mode is not the
default because it is much slower.
File: elisp, Node: Resources, Next: Rebinding X Keys, Prev: X Connections, Up: X Server
Resources
---------
- Function: x-get-resource ATTRIBUTE &optional NAME CLASS
The function `x-get-resource' retrieves a resource value from the X
Windows defaults database.
Resources are indexed by a combination of a "key" and a "class".
This function searches using a key of the form
`INSTANCE.ATTRIBUTE', where INSTANCE is the name under which Emacs
was invoked, and uses `Emacs' as the class.
The optional arguments COMPONENT and SUBCLASS add to the key and
the class, respectively. You must specify both of them or neither.
If you specify them, the key is `INSTANCE.COMPONENT.ATTRIBUTE',
and the class is `Emacs.SUBCLASS'.
File: elisp, Node: Rebinding X Keys, Next: Server Data, Prev: Resources, Up: X Server
Rebinding X Server Keys
-----------------------
The X server allows each client to specify what sequence of
characters each keyboard key should generate, depending on the set of
shift keys held down. Emacs has functions to redefine these sequences
in the X server. Redefinitions via `x-rebind-key' apply only to Emacs.
Other clients using the same X server are not affected.
- Function: x-rebind-key KEYSYM MODIFIERS NEWSTRING
This function redefines a keyboard key in the X server. KEYSYM is
a string which conforms to the X keysym definitions found in
`X11/keysymdef.h', but without the prefix `XK_'. MODIFIERS is
either `nil', meaning no modifier keys, or a list of names of
modifier keys, again using the names from `X11/keysymdef.h' but
without the `XK_' prefix.
The third argument, NEWSTRING, is the new definition of the key.
It is the sequence of characters that the key should produce as
input.
For example,
(x-rebind-key "F1" nil "abc")
causes the F1 function key to generate the string `"abc"'.
Similarly,
(x-rebind-key "BackSpace"
(list "Shift" "Control_L" "c-s-BackSpace")
makes the BS key send the string `"c-s-BackSpace"' if either the
shift key or the left-hand control key is held down.
- Function: x-rebind-keys KEYSYM STRINGS
This function redefines the complete meaning of a single keyboard
key, specifying the behavior for each of the 16 shift masks
independently.
The argument KEYSYM specifies the key to rebind, as in
`x-rebind-key'.
The argument STRINGS is a list of 16 elements, one for each
possible shift mask value; the Nth element says how to redefine
the key KEYCODE with shift mask value N. If element N is a
string, it is the new definition for shift mask N. If element N
is `nil', the definition for shift mask N is unchanged.
File: elisp, Node: Server Data, Prev: Rebinding X Keys, Up: X Server
Data about the X Server
-----------------------
This section describes functions and a variable that you can use to
get information about the capabilities and origin of the X server that
Emacs is displaying its frames on.
- Function: x-display-screens
This function returns the number of screens associated with the
current display.
- Function: x-server-version
This function returns the list of version numbers of the X server
in use.
- Function: x-server-vendor
This function returns the vendor supporting the X server in use.
- Function: x-display-pixel-height
This function returns the height of this X screen in pixels.
- Function: x-display-mm-height
This function returns the height of this X screen in millimeters.
- Function: x-display-pixel-width
This function returns the width of this X screen in pixels.
- Function: x-display-mm-width
This function returns the width of this X screen in millimeters.
- Function: x-display-backing-store
This function returns the backing store capability of this screen.
Values can be the symbols `always', `when-mapped', or `not-useful'.
- Function: x-display-save-under
This function returns non-`nil' if this X screen supports the
SaveUnder feature.
- Function: x-display-planes
This function returns the number of planes this display supports.
- Function: x-display-visual-class
This function returns the visual class for this X screen. The
value is one of the symbols `static-gray', `gray-scale',
`static-color', `pseudo-color', `true-color', and `direct-color'.
- Function: x-display-color-p
This function returns `t' if the X screen in use is a color screen.
- Function: x-display-color-cells
This function returns the number of color cells this X screen
supports.
- Variable: x-no-window-manager
This variable's value is is `t' if no X window manager is in use.
File: elisp, Node: Positions, Next: Markers, Prev: Frames, Up: Top
Positions
*********
A "position" is the index of a character in the text of buffer.
More precisely, a position identifies the place between two characters
(or before the first character, or after the last character), so we can
speak of the character before or after a given position. However, the
character after a position is often said to be "at" that position.
Positions are usually represented as integers starting from 1, but
can also be represented as "markers"--special objects which relocate
automatically when text is inserted or deleted so they stay with the
surrounding characters. *Note Markers::.
* Menu:
* Point:: The special position where editing takes place.
* Motion:: Changing point.
* Excursions:: Temporary motion and buffer changes.
* Narrowing:: Restricting editing to a portion of the buffer.
File: elisp, Node: Point, Next: Motion, Prev: Positions, Up: Positions
Point
=====
"Point" is a special buffer position used by many editing commands,
including the self-inserting typed characters and text insertion
functions. Other commands move point through the text to allow editing
and insertion at different places.
Like other positions, point designates a place between two characters
(or before the first character, or after the last character), rather
than a particular character. Many terminals display the cursor over the
character that immediately follows point; on such terminals, point is
actually before the character on which the cursor sits.
The value of point is a number between 1 and the buffer size plus 1.
If narrowing is in effect (*note Narrowing::.), then point is
constrained to fall within the accessible portion of the buffer
(possibly at one end of it).
Each buffer has its own value of point, which is independent of the
value of point in other buffers. Each window also has a value of point,
which is independent of the value of point in other windows on the same
buffer. This is why point can have different values in various windows
that display the same buffer. When a buffer appears in only one window,
the buffer's point and the window's point normally have the same value,
so the distinction is rarely important. *Note Window Point::, for more
details.
- Function: point
This function returns the position of point in the current buffer,
as an integer.
(point)
=> 175
- Function: point-min
This function returns the minimum accessible value of point in the
current buffer. This is 1, unless narrowing is in effect, in
which case it is the position of the start of the region that you
narrowed to. (*Note Narrowing::.)
- Function: point-max
This function returns the maximum accessible value of point in the
current buffer. This is `(1+ (buffer-size))', unless narrowing is
in effect, in which case it is the position of the end of the
region that you narrowed to. (*Note Narrowing::).
- Function: buffer-end FLAG
This function returns `(point-min)' if FLAG is less than 1,
`(point-max)' otherwise. The argument FLAG must be a number.
- Function: buffer-size
This function returns the total number of characters in the current
buffer. In the absence of any narrowing (*note Narrowing::.),
`point-max' returns a value one larger than this.
(buffer-size)
=> 35
(point-max)
=> 36
- Variable: buffer-saved-size
The value of this buffer-local variable is the former length of the
current buffer, as of the last time it was read in, saved or
auto-saved.
File: elisp, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
Motion
======
Motion functions change the value of point, either relative to the
current value of point, relative to the beginning or end of the buffer,
or relative to the edges of the selected window. *Note Point::.
* Menu:
* Character Motion:: Moving in terms of characters.
* Word Motion:: Moving in terms of words.
* Buffer End Motion:: Moving to the beginning or end of the buffer.
* Text Lines:: Moving in terms of lines of text.
* Screen Lines:: Moving in terms of lines as displayed.
* Vertical Motion:: Implementation of `next-line' and
`previous-line'.
* List Motion:: Moving by parsing lists and sexps.
* Skipping Characters:: Skipping characters belonging to a certain set.
File: elisp, Node: Character Motion, Next: Word Motion, Prev: Motion, Up: Motion
Motion by Characters
--------------------
These functions move point based on a count of characters.
`goto-char' is a fundamental primitive because it is the way to move
point to a specified position.
- Command: goto-char POSITION
This function sets point in the current buffer to the value
POSITION. If POSITION is less than 1, then point is set to the
beginning of the buffer. If it is greater than the length of the
buffer, then point is set to the end of the buffer.
If narrowing is in effect, then the position is still measured
from the beginning of the buffer, but point cannot be moved
outside of the accessible portion. Therefore, if POSITION is too
small, point is set to the beginning of the accessible portion of
the text; if POSITION is too large, point is set to the end.
When this function is called interactively, POSITION is the
numeric prefix argument, if provided; otherwise it is read from the
minibuffer.
`goto-char' returns POSITION.
- Command: forward-char &optional COUNT
This function moves point forward, towards the end of the buffer,
COUNT characters (or backward, towards the beginning of the
buffer, if COUNT is negative). If the function attempts to move
point past the beginning or end of the buffer (or the limits of the
accessible portion, when narrowing is in effect), an error is
signaled with error code `beginning-of-buffer' or `end-of-buffer'.
In an interactive call, COUNT is the numeric prefix argument.
- Command: backward-char &optional COUNT
This function moves point backward, towards the beginning of the
buffer, COUNT characters (or forward, towards the end of the
buffer, if COUNT is negative). If the function attempts to move
point past the beginning or end of the buffer (or the limits of
the accessible portion, when narrowing is in effect), an error is
signaled with error code `beginning-of-buffer' or `end-of-buffer'.
In an interactive call, COUNT is the numeric prefix argument.
File: elisp, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
Motion by Words
---------------
These functions for parsing words use the syntax table to decide
whether a given character is part of a word. *Note Syntax Tables::.
- Command: forward-word COUNT
This function moves point forward COUNT words (or backward if
COUNT is negative). Normally it returns `t'. If this motion
encounters the beginning or end of the buffer, or the limits of the
accessible portion when narrowing is in effect, point stops there
and the value is `nil'.
In an interactive call, COUNT is set to the numeric prefix
argument.
- Command: backward-word COUNT
This function just like `forward-word', except that it moves
backward until encountering the front of a word, rather than
forward.
In an interactive call, COUNT is set to the numeric prefix
argument.
This function is rarely used in programs, as it is more efficient
to call `forward-word' with negative argument.
- Variable: words-include-escapes
This variable affects the behavior of `forward-word' and everything
that uses it. If it is non-`nil', then characters in the "escape"
and "character quote" syntax classes count as part of words.
Otherwise, they do not.
File: elisp, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
Motion to an End of the Buffer
------------------------------
To move point to the beginning of the buffer, write:
(goto-char (point-min))
Likewise, to move to the end of the buffer, use:
(goto-char (point-max))
Here are two commands which users use to do these things. They are
documented here to warn you not to use them in Lisp programs, because
they set the mark and display messages in the echo area.
- Command: beginning-of-buffer &optional N
This function moves point to the beginning of the buffer (or the
limits of the accessible portion, when narrowing is in effect),
setting the mark at the previous position. If N is non-`nil',
then it puts point N tenths of the way from the beginning of the
buffer.
In an interactive call, N is the numeric prefix argument, if
provided; otherwise N defaults to `nil'.
Don't use this function in Lisp programs!
- Command: end-of-buffer &optional N
This function moves point to the end of the buffer (or the limits
of the accessible portion, when narrowing is in effect), setting
the mark at the previous position. If N is non-`nil', then it puts
point N tenths of the way from the end.
In an interactive call, N is the numeric prefix argument, if
provided; otherwise N defaults to `nil'.
Don't use this function in Lisp programs!
File: elisp, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
Motion by Text Lines
--------------------
Text lines are portions of the buffer delimited by newline
characters, which are regarded as part of the previous line. The first
text line begins at the beginning of the buffer, and the last text line
ends at the end of the buffer whether or not the last character is a
newline. The division of the buffer into text lines is not affected by
the width of the window, or by how tabs and control characters are
displayed.
- Command: goto-line LINE
This function moves point to the front of the LINEth line,
counting from line 1 at beginning of buffer. If LINE is less than
1, then point is set to the beginning of the buffer. If LINE is
greater than the number of lines in the buffer, then point is set
to the *end of the last line* of the buffer.
If narrowing is in effect, then LINE still counts from the
beginning of the buffer, but point cannot go outside the accessible
portion. So point is set at the beginning or end of the accessible
portion of the text if the line number specifies a position that is
inaccessible.
The return value of `goto-line' is the difference between LINE and
the line number of the line to which point actually was able move
(before taking account of any narrowing). Thus, the value is
positive if the scan encounters the end of the buffer.
In an interactive call, LINE is the numeric prefix argument if one
has been provided. Otherwise LINE is read in the minibuffer.
- Command: beginning-of-line &optional COUNT
This function moves point to the beginning of the current line.
With an argument COUNT not `nil' or 1, it moves forward COUNT-1
lines and then to the beginning of the line.
If this function reaches the end of the buffer (or of the
accessible portion, if narrowing is in effect), it positions point
at the beginning of the last line. No error is signaled.
- Command: end-of-line &optional COUNT
This function moves point to the end of the current line. With an
argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
then to the end of the line.
If this function reaches the end of the buffer (or of the
accessible portion, if narrowing is in effect), it positions point
at the end of the last line. No error is signaled.
- Command: forward-line &optional COUNT
This function moves point forward COUNT lines, to the beginning of
the line. If COUNT is negative, it moves point -COUNT lines
backward, to the beginning of the line.
If the beginning or end of the buffer (or of the accessible
portion) is encountered before that many lines are found, then
point stops at the beginning or end. No error is signaled.
`forward-line' returns the difference between COUNT and the number
of lines actually moved. If you attempt to move down five lines
from the beginning of a buffer that has only three lines, point
will positioned at the end of the last line, and the value will be
2.
In an interactive call, COUNT is the numeric prefix argument.
- Function: count-lines START END
This function returns the number of lines between the positions
START and END in the current buffer. If START and END are equal,
then it returns 0. Otherwise it returns at least 1, even if START
and END are on the same line. This is because the text between
them, considered in isolation, must contain at least one line
unless it is empty.
Here is an example of using `count-lines':
(defun current-line ()
"Return the vertical position of point
in the selected window. Top line is 0.
Counts each text line only once, even if it wraps."
(+ (count-lines (window-start) (point))
(if (= (current-column) 0) 1 0)
-1))
Also see the functions `bolp' and `eolp' in *Note Near Point::.
These functions do not move point, but test whether it is already at the
beginning or end of a line.
File: elisp, Node: Screen Lines, Next: Vertical Motion, Prev: Text Lines, Up: Motion
Motion by Screen Lines
----------------------
The line functions in the previous section count text lines,
delimited only by newline characters. By contrast, these functions
count screen lines, which are defined by the way the text appears on
the screen. A text line is a single screen line if it is short enough
to fit the width of the selected window, but otherwise it may occupy
several screen lines.
In some cases, text lines are truncated on the screen rather than
continued onto additional screen lines. Then `vertical-motion' moves
point just like `forward-line'. *Note Truncation::.
Because the width of a given string depends on the flags which
control the appearance of certain characters, `vertical-motion' will
behave differently on a given piece of text found in different buffers.
It will even act differently in different windows showing the same
buffer, because the width may differ and so may the truncation flag.
*Note Usual Display::.
- Function: vertical-motion COUNT
This function moves point to the start of the screen line COUNT
screen lines down from the screen line containing point. If COUNT
is negative, it moves up instead.
This function returns the number of lines moved. The value may be
less in absolute value than COUNT if the beginning or end of the
buffer was reached.
- Command: move-to-window-line COUNT
This function moves point with respect to the text currently
displayed in the selected window. Point is moved to the beginning
of the screen line COUNT screen lines from the top of the window.
If COUNT is negative, point moves either to the beginning of the
line -COUNT lines from the bottom or else to the last line of the
buffer if the buffer ends above the specified screen position.
If COUNT is `nil', then point moves to the beginning of the line
in the middle of the window. If the absolute value of COUNT is
greater than the size of the window, then point moves to the place
which would appear on that screen line if the window were tall
enough. This will probably cause the next redisplay to scroll to
bring that location onto the screen.
In an interactive call, COUNT is the numeric prefix argument.
The value returned is the window line number, with the top line in
the window numbered 0.
File: elisp, Node: Vertical Motion, Next: List Motion, Prev: Screen Lines, Up: Motion
The User-Level Vertical Motion Commands
---------------------------------------
A goal column is useful if you want to edit text such as a table in
which you want to move point to a certain column on each line. The goal
column affects the vertical text line motion commands, `next-line' and
`previous-line'. *Note Basic Editing Commands: (emacs)Basic.
- User Option: goal-column
This variable holds an explicitly specified goal column for
vertical line motion commands. If it is an integer, it specifies
a column, and these commands try to move to that column on each
line. If it is `nil', then the commands set their own goal
columns. Any other value is invalid.
- Variable: temporary-goal-column
This variable holds the temporary goal column during a sequence of
consecutive vertical line motion commands. It is overridden by
`goal-column' if that is non-`nil'. It is set each time a
vertical motion command is invoked, unless the previous command
was also a vertical motion command.
- User Option: track-eol
This variable controls how the vertical line motion commands
operate when starting at the end of a line. If `track-eol' is
non-`nil', then vertical motion starting at the end of a line will
keep to the ends of lines. This means moving to the end of each
line moved onto. The value of `track-eol' has no effect if point
is not at the end of a line when the first vertical motion command
is given.
`track-eol' has its effect by causing `temporary-goal-column' to
be set to 9999 instead of to the current column.
- Command: set-goal-column UNSET
This command sets the variable `goal-column' to specify a permanent
goal column for the vertical line motion commands. If UNSET is
`nil', then `goal-column' is set to the current column of point.
If UNSET is non-`nil', then `goal-column' is set to `nil'.
This function is intended for interactive use; and in an
interactive call, UNSET is the raw prefix argument.
File: elisp, Node: List Motion, Next: Skipping Characters, Prev: Vertical Motion, Up: Motion
Moving over Balanced Expressions
--------------------------------
Here are several functions concerned with balanced-parenthesis
expressions (also called "sexps" in connection with moving across them
in Emacs). The syntax table controls how these functions interpret
various characters; see *Note Syntax Tables::. *Note Parsing
Expressions::, for lower-level primitives for scanning sexps or parts of
sexps. For user-level commands, see *Note Lists and Sexps:
(emacs)Lists and Sexps.
- Command: forward-list ARG
Move forward across ARG balanced groups of parentheses. (Other
syntactic entities such as words or paired string quotes are
ignored.)
- Command: backward-list ARG
Move backward across ARG balanced groups of parentheses. (Other
syntactic entities such as words or paired string quotes are
ignored.)
- Command: up-list ARG
Move forward out of ARG levels of parentheses. A negative
argument means move backward but still to a less deep spot.
- Command: down-list ARG
Move forward down ARG levels of parentheses. A negative argument
means move backward but still go down ARG level.
- Command: forward-sexp ARG
Move forward across ARG balanced expressions. Balanced
expressions include both those delimited by parentheses and other
kinds, such as words and string constants. For example,
---------- Buffer: foo ----------
(concat-!- "foo " (car x) y z)
---------- Buffer: foo ----------
(forward-sexp 3)
=> nil
---------- Buffer: foo ----------
(concat "foo " (car x) y-!- z)
---------- Buffer: foo ----------
- Command: backward-sexp ARG
Move backward across ARG balanced expressions.